home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / c++ / filebuf.z / filebuf
Encoding:
Text File  |  2002-10-03  |  11.1 KB  |  176 lines
  1. FILEBUF(3C)                                           Last changed: 1-14-99
  2.  
  3.  
  4. NNAAMMEE
  5.      ffiilleebbuuff - Buffer for file I/O
  6.  
  7. SSYYNNOOPPSSIISS
  8.      ##iinncclluuddee <<iioossttrreeaamm..hh>>
  9.  
  10.      ttyyppeeddeeff lloonngg ssttrreeaammooffff,, ssttrreeaammppooss;;
  11.      ccllaassss iiooss {{
  12.      ppuubblliicc::
  13.           eennuumm sseeeekk__ddiirr {{ bbeegg,, ccuurr,, eenndd }};;
  14.           eennuumm ooppeenn__mmooddee {{ iinn,, oouutt,, aattee,, aapppp,, ttrruunncc,, nnooccrreeaattee,, nnoorreeppllaaccee }}
  15.      ;;
  16.           //ee aanndd lloottss ooff ootthheerr ssttuuffff,, sseeee iiooss((33CC)) ......
  17.      }} ;;
  18.  
  19.      ##iinncclluuddee <<ffssttrreeaamm..hh>>
  20.  
  21.      ccllaassss ffiilleebbuuff :: ppuubblliicc ssttrreeaammbbuuff {{
  22.      ppuubblliicc::
  23.           ssttaattiicc ccoonnsstt iinntt ooppeennpprroott ;; //** ddeeffaauulltt pprrootteeccttiioonn ffoorr ooppeenn **//
  24.  
  25.                ffiilleebbuuff(()) ;;
  26.                ~~ffiilleebbuuff(()) ;;
  27.                ffiilleebbuuff((iinntt dd));;
  28.                ffiilleebbuuff((iinntt dd,, cchhaarr**  pp,, iinntt lleenn)) ;;
  29.  
  30.           ffiilleebbuuff**  aattttaacchh((iinntt dd)) ;;
  31.           ffiilleebbuuff**  cclloossee(());;
  32.           iinntt  ffdd(());;
  33.           iinntt  iiss__ooppeenn(());;
  34.           ffiilleebbuuff**  ooppeenn((cchhaarr **nnaammee,, iinntt oommooddee,, iinntt pprroott==ooppeennpprroott)) ;;
  35.           ssttrreeaammppooss sseeeekkooffff((ssttrreeaammooffff,, sseeeekk__ddiirr,, iinntt oommooddee)) ;;
  36.           ssttrreeaammppooss sseeeekkppooss((ssttrreeaammppooss,, iinntt oommooddee)) ;;
  37.           ssttrreeaammbbuuff**     sseettbbuuff((cchhaarr** pp,, iinntt lleenn)) ;;
  38.           iinntt  ssyynncc(()) ;;
  39.      }};;
  40.  
  41. IIMMPPLLEEMMEENNTTAATTIIOONN
  42.      IRIX systems
  43.  
  44. DDEESSCCRRIIPPTTIIOONN
  45.      A ffiilleebbuuff specializes a ssttrreeaammbbuuff to use a file as a source or sink of
  46.      characters.  Characters are consumed by doing writes to the file, and
  47.      are produced by doing reads.  When the file is seekable, a ffiilleebbuuff
  48.      allows seeks.  At least 4 characters of putback are guaranteed.  When
  49.      the file permits reading and writing, the ffiilleebbuuff permits both storing
  50.      and fetching.  No special action is required between gets and puts
  51.      (unlike stdio).  A ffiilleebbuuff that is connected to a file descriptor is
  52.      said to be open.  Files are opened with a protection mode of ooppeennpprroott
  53.      (0644), which is the default.
  54.  
  55.      The _r_e_s_e_r_v_e _a_r_e_a (or buffer, see ssbbuuff..ppuubb(3C) and ssbbuuff..pprroott(3C)) is
  56.      allocated automatically if one is not specified explicitly with a
  57.      constructor or a call to sseettbbuuff(()).  A ffiilleebbuuff can also be made
  58.      uunnbbuuffffeerreedd with certain arguments to the constructor or sseettbbuuff(()), in
  59.      which case a system call is made for each character that is read or
  60.      written.  The ggeett and ppuutt pointers into the reserve area are
  61.      conceptually tied together; they behave as a single pointer.
  62.      Therefore, the following descriptions refer to a single get/put
  63.      pointer.
  64.  
  65.      In the following descriptions, the following assumptions are made:
  66.  
  67.      * _f is a ffiilleebbuuff.
  68.  
  69.      * _p_f_b is a ffiilleebbuuff**.
  70.  
  71.      * _p_s_b is a ssttrreeaammbbuuff**.
  72.  
  73.      * _i, _d, _l_e_n, and _p_r_o_t are iinntts.
  74.  
  75.      * _n_a_m_e and _p_t_r are cchhaarr**s.
  76.  
  77.      * _m_o_d_e is an iinntt representing an ooppeenn__mmooddee.
  78.  
  79.      * _o_f_f is a ssttrreeaammooffff.
  80.        - _p and _p_o_s are ssttrreeaammppooss's.
  81.        - _d_i_r is a sseeeekk__ddiirr.
  82.  
  83.      Constructors:
  84.  
  85.      ffiilleebbuuff(())
  86.           Constructs an initially closed ffiilleebbuuff.
  87.  
  88.      ffiilleebbuuff((_d))
  89.           Constructs a ffiilleebbuuff connected to file descriptor _d.
  90.  
  91.      ffiilleebbuuff((_d,, _p,, _l_e_n))
  92.           Constructs a ffiilleebbuuff connected to file descriptor _d and
  93.           initialized to use the reserve area starting at _p and containing
  94.           _l_e_n bytes.  If _p is null or _l_e_n is zero or less, the ffiilleebbuuff will
  95.           be unbuffered.
  96.  
  97.      Members:
  98.  
  99.      _p_f_b==_f..aattttaacchh((_d))
  100.           Connects _f to an open file descriptor, _d.  aattttaacchh(()) normally
  101.           returns &&_f,, bbuutt rreettuurrnnss 00 iiff _f iiss aallrreeaaddyy ooppeenn..
  102.  
  103.      _p_f_b==_f..cclloossee(())
  104.           Flushes any waiting output, closes the file descriptor, and
  105.           disconnects _f.  Unless an error occurs, _f's error state will be
  106.           cleared.  cclloossee(()) returns &&_f uunnlleessss eerrrroorrss ooccccuurr,, iinn wwhhiicchh ccaassee
  107.           iitt rreettuurrnnss 00..  EEvveenn iiff eerrrroorrss ooccccuurr,, cclloossee(()) lleeaavveess tthhee ffiillee
  108.           ddeessccrriippttoorr aanndd _f cclloosseedd..
  109.  
  110.      _i==_f..ffdd(())
  111.           Returns _i, the file descriptor _f is connected to.  If _f is
  112.           closed, _i is EEOOFF.
  113.  
  114.      _i==_f..iiss__ooppeenn(())
  115.           Returns non-zero when _f is connected to a file descriptor, and
  116.           zero otherwise.
  117.  
  118.      _p_f_b==_f..ooppeenn((_n_a_m_e,, _m_o_d_e,, _p_r_o_t))
  119.           Opens file _n_a_m_e and connects _f to it.  If the file does not
  120.           already exist, an attempt is made to create it with protection
  121.           mode _p_r_o_t, unless iiooss::::nnooccrreeaattee is specified in _m_o_d_e.  By
  122.           default, _p_r_o_t is ffiilleebbuuff::::ooppeennpprroott, which is 0644.  Failure
  123.           occurs if _f is already open.  ooppeenn(()) normally returns &&_f,, bbuutt iiff
  124.           aann eerrrroorr ooccccuurrss iitt rreettuurrnnss 00..  TThhee mmeemmbbeerrss ooff ooppeenn__mmooddee aarree bbiittss
  125.           tthhaatt mmaayy bbee oorr''eedd ttooggeetthheerr..  ((BBeeccaauussee tthhee oorr''iinngg rreettuurrnnss aann iinntt,,
  126.           ooppeenn(()) ttaakkeess aann iinntt rraatthheerr tthhaann aann ooppeenn__mmooddee aarrgguummeenntt..))  TThhee
  127.           mmeeaanniinnggss ooff tthheessee bbiittss iinn _m_o_d_e aarree ddeessccrriibbeedd iinn ddeettaaiill iinn
  128.           ffssttrreeaamm((33CC))..
  129.  
  130.      _p==_f..sseeeekkooffff((_o_f_f,, _d_i_r,, _m_o_d_e))
  131.           Moves the get/put pointer as designated by _o_f_f and _d_i_r.  It may
  132.           fail if the file that _f is attached to does not support seeking,
  133.           or if the attempted motion is otherwise invalid (such as
  134.           attempting to seek to a position before the beginning of file).
  135.           _o_f_f is interpreted as a count relative to the place in the file
  136.           specified by _d_i_r as described in ssbbuuff..ppuubb(3C).  _m_o_d_e is ignored.
  137.           sseeeekkooffff(()) returns _p, the new position, or EEOOFF if a failure
  138.           occurs.  The position of the file after a failure is undefined.
  139.  
  140.      _p==_f..sseeeekkppooss((_p_o_s,, _m_o_d_e))
  141.           Moves the file to a position _p_o_s as described in ssbbuuff..ppuubb(3C).
  142.           _m_o_d_e is ignored.  sseeeekkppooss(()) normally returns _p_o_s, but on failure
  143.           it returns EEOOFF.
  144.  
  145.      _p_s_b==_f..sseettbbuuff((_p_t_r,, _l_e_n))
  146.           Sets up the reserve area as _l_e_n bytes beginning at _p_t_r.  If _p_t_r
  147.           is null or _l_e_n is less than or equal to 0, _f will be unbuffered.
  148.           sseettbbuuff(()) normally returns &&_f..  HHoowweevveerr,, iiff _f iiss ooppeenn aanndd aa bbuuffffeerr
  149.           hhaass bbeeeenn aallllooccaatteedd,, nnoo cchhaannggeess aarree mmaaddee ttoo tthhee rreesseerrvvee aarreeaa oorr ttoo
  150.           tthhee bbuuffffeerriinngg ssttaattuuss,, aanndd sseettbbuuff(()) rreettuurrnnss 00..
  151.  
  152.      _i==_f..ssyynncc(())
  153.           Attempts to force the state of the get/put pointer of f to agree
  154.           (be synchronized) with the state of the file _f..ffdd(()).  _T_h_i_s _m_e_a_n_s
  155.           _i_t _m_a_y _w_r_i_t_e _c_h_a_r_a_c_t_e_r_s _t_o _t_h_e _f_i_l_e _i_f _s_o_m_e _h_a_v_e _b_e_e_n _b_u_f_f_e_r_e_d
  156.           _f_o_r _o_u_t_p_u_t _o_r _a_t_t_e_m_p_t _t_o _r_e_p_o_s_i_t_i_o_n (_s_e_e_k) _t_h_e _f_i_l_e _i_f _c_h_a_r_a_c_t_e_r_s
  157.           _h_a_v_e _b_e_e_n _r_e_a_d _a_n_d _b_u_f_f_e_r_e_d _f_o_r _i_n_p_u_t.  _N_o_r_m_a_l_l_y, ssyynncc(()) _r_e_t_u_r_n_s
  158.           _0, _b_u_t _i_t _r_e_t_u_r_n_s EEOOFF _i_f _s_y_n_c_h_r_o_n_i_z_a_t_i_o_n _i_s _n_o_t _p_o_s_s_i_b_l_e.
  159.  
  160.           _S_o_m_e_t_i_m_e_s _i_t _i_s _n_e_c_e_s_s_a_r_y _t_o _g_u_a_r_a_n_t_e_e _t_h_a_t _c_e_r_t_a_i_n _c_h_a_r_a_c_t_e_r_s
  161.           _a_r_e _w_r_i_t_t_e_n _t_o_g_e_t_h_e_r.  _T_o _d_o _t_h_i_s, _t_h_e _p_r_o_g_r_a_m _s_h_o_u_l_d _u_s_e
  162.           sseettbbuuff(()) (_o_r _a _c_o_n_s_t_r_u_c_t_o_r) _t_o _g_u_a_r_a_n_t_e_e _t_h_a_t _t_h_e _r_e_s_e_r_v_e _a_r_e_a _i_s
  163.           _a_t _l_e_a_s_t _a_s _l_a_r_g_e _a_s _t_h_e _n_u_m_b_e_r _o_f _c_h_a_r_a_c_t_e_r_s _t_h_a_t _m_u_s_t _b_e
  164.           _w_r_i_t_t_e_n _t_o_g_e_t_h_e_r.  _I_t _c_a_n _t_h_e_n _c_a_l_l ssyynncc(()), _t_h_e_n _s_t_o_r_e _t_h_e
  165.           _c_h_a_r_a_c_t_e_r_s, _t_h_e_n _c_a_l_l ssyynncc(()) _a_g_a_i_n.
  166.  
  167. NNOOTTEESS
  168.      There is no way to force atomic reads.
  169.  
  170.      ffiilleebbuuff does not report failures of seek (for example, on a tty).
  171.  
  172. SSEEEE AALLSSOO
  173.      ssbbuuff..ppuubb(3C), ssbbuuff..pprroott(3C), ffssttrreeaamm(3C)
  174.  
  175.      This man page is available only online.
  176.